<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>granule</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="OpcodesTop.html" title="Orchestra Opcodes and Operators" />
    <link rel="prev" href="grain3.html" title="grain3" />
    <link rel="next" href="guiro.html" title="guiro" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">granule</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="grain3.html">Prev</a> </td>
          <th width="60%" align="center">Orchestra Opcodes and Operators</th>
          <td width="20%" align="right"> <a accesskey="n" href="guiro.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="refentry">
      <a id="granule"></a>
      <div class="titlepage"></div>
      <a id="IndexGranule" class="indexterm"></a>
      <div class="refnamediv">
        <h2>
          <span class="refentrytitle">granule</span>
        </h2>
        <p>granule — 
      A more complex granular synthesis texture generator.
          </p>
      </div>
      <div class="refsect1">
        <a id="idp113606592"></a>
        <h2>Description</h2>
        <p>
      The <span class="emphasis"><em>granule</em></span> unit generator is more complex than <span class="emphasis"><em>grain</em></span>, but does add new possibilities.
    </p>
        <p>
      <span class="emphasis"><em>granule</em></span> is a Csound unit generator which employs a wavetable as input to produce granularly synthesized audio output. Wavetable data may be generated by any of the GEN subroutines such as <a class="link" href="GEN01.html" title="GEN01"><em class="citetitle">GEN01</em></a> which reads an audio data file into a wavetable. This enable a sampled sound to be used as the source for the grains. Up to 128 voices are implemented internally. The maximum number of voices can be increased by redefining the variable MAXVOICE in the grain4.h file. <span class="emphasis"><em>granule</em></span> has a build-in random number generator to handle all the random offset parameters. Thresholding is also implemented to scan the source function table at initialization stage. This facilitates features such as skipping silence passage between sentences.
    </p>
        <p>
      The characteristics of the synthesis are controlled by 22 parameters. <span class="emphasis"><em>xamp</em></span> is the amplitude of the output and it can be either audio rate or control rate variable.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp113613072"></a>
        <h2>Syntax</h2>
        <pre class="synopsis">ares <span class="command"><strong>granule</strong></span> xamp, ivoice, iratio, imode, ithd, ifn, ipshift, igskip, \
      igskip_os, ilength, kgap, igap_os, kgsize, igsize_os, iatt, idec \
      [, iseed] [, ipitch1] [, ipitch2] [, ipitch3] [, ipitch4] [, ifnenv]</pre>
      </div>
      <div class="refsect1">
        <a id="idp113615568"></a>
        <h2>Initialization</h2>
        <p>
      <span class="emphasis"><em>ivoice</em></span> -- number of voices.
    </p>
        <p>
      <span class="emphasis"><em>iratio</em></span> -- ratio of the speed of the gskip pointer relative to output audio sample rate. eg. 0.5 will be half speed.
    </p>
        <p>
      <span class="emphasis"><em>imode</em></span> -- +1 grain pointer move forward (same direction of the gskip pointer), -1 backward (oppose direction to the gskip pointer) or 0 for random.
    </p>
        <p>
      <span class="emphasis"><em>ithd</em></span> -- threshold, if the sampled signal in the wavetable is smaller then <span class="emphasis"><em>ithd</em></span>, it will be skipped.
    </p>
        <p>
      <span class="emphasis"><em>ifn</em></span> -- function table number of sound source.
    </p>
        <p>
      <span class="emphasis"><em>ipshift</em></span> -- pitch shift control. If <span class="emphasis"><em>ipshift</em></span> is 0, pitch will be set randomly up and down an octave. If <span class="emphasis"><em>ipshift</em></span> is 1, 2, 3 or 4, up to four different pitches can be set amount the number of voices defined in <span class="emphasis"><em>ivoice</em></span>. The optional parameters <span class="emphasis"><em>ipitch1</em></span>, <span class="emphasis"><em>ipitch2</em></span>, <span class="emphasis"><em>ipitch3</em></span> and <span class="emphasis"><em>ipitch4</em></span> are used to quantify the pitch shifts.
    </p>
        <p>
      <span class="emphasis"><em>igskip</em></span> -- initial skip from the beginning of the function table in sec.
    </p>
        <p>
      <span class="emphasis"><em>igskip_os</em></span> -- gskip pointer random offset in sec, 0 will be no offset.
    </p>
        <p>
      <span class="emphasis"><em>ilength</em></span> -- length of the table to be used starting from <span class="emphasis"><em>igskip</em></span> in sec.
    </p>
        <p>
      <span class="emphasis"><em>igap_os</em></span> -- gap random offset in % of the gap size, 0 gives no offset.
    </p>
        <p>
      <span class="emphasis"><em>igsize_os</em></span> -- grain size random offset in % of grain size, 0 gives no offset.
    </p>
        <p>
      <span class="emphasis"><em>iatt</em></span> -- attack of the grain envelope in % of grain size.
    </p>
        <p>
      <span class="emphasis"><em>idec</em></span> -- decade of the grain envelope in % of grain size.
    </p>
        <p>
      <span class="emphasis"><em>iseed</em></span> (optional, default=0.5) -- seed for the random number generator.
    </p>
        <p>
      <span class="emphasis"><em>ipitch1, ipitch2, ipitch3, ipitch4</em></span> (optional, default=1) -- pitch shift parameter, used when <span class="emphasis"><em>ipshift</em></span> is set to 1, 2, 3 or 4. Time scaling technique is used in pitch shift with linear interpolation between data points. Default value is 1, the original pitch.
    </p>
        <p>
      <span class="emphasis"><em>ifnenv</em></span> (optional, default=0) -- function table number to be used to generate the shape of the envelope.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp113636816"></a>
        <h2>Performance</h2>
        <p>
      <span class="emphasis"><em>xamp</em></span> -- amplitude.
    </p>
        <p>
      <span class="emphasis"><em>kgap</em></span> -- gap between grains in sec.
    </p>
        <p>
      <span class="emphasis"><em>kgsize</em></span> -- grain size in sec.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp113640304"></a>
        <h2>Examples</h2>
        <p>
      Here is an example of the granule opcode. It uses the file <a class="ulink" href="examples/granule.csd" target="_top"><em class="citetitle">granule.csd</em></a>, and <a class="ulink" href="examples/mary.wav" target="_top"><em class="citetitle">mary.wav</em></a>.

      </p>
        <div class="example">
          <a id="idp113643008"></a>
          <p class="title">
            <strong>Example 360. Example of the granule opcode.</strong>
          </p>
          <div class="example-contents">
            <p>See the sections <a class="link" href="UsingRealTime.html" title="Real-Time Audio"><em class="citetitle">Real-time Audio</em></a> and <a class="link" href="CommandFlags.html" title="Csound command line"><em class="citetitle">Command Line Flags</em></a> for more information on using command line flags.</p>
            <pre class="programlisting">
<span class="csdtag">&lt;CsoundSynthesizer&gt;</span>
<span class="csdtag">&lt;CsOptions&gt;</span>
<span class="comment">; Select audio/midi flags here according to platform</span>
<span class="comment">; Audio out   Audio in    No messages</span>
-odac           -iadc     -d     <span class="comment">;;;RT audio I/O</span>
<span class="comment">; For Non-realtime ouput leave only the line below:</span>
<span class="comment">; -o granule.wav -W ;;; for file output any platform</span>
<span class="csdtag">&lt;/CsOptions&gt;</span>
<span class="csdtag">&lt;CsInstruments&gt;</span>

<span class="ohdr">sr</span> <span class="op">=</span> 44100
<span class="ohdr">kr</span> <span class="op">=</span> 4410
<span class="ohdr">ksmps</span> <span class="op">=</span> 10
<span class="ohdr">nchnls</span> <span class="op">=</span> 2
<span class="oblock">instr</span> 1
<span class="comment">;</span>
k1      <span class="opc">linseg</span> 0,0.5,1,(p3<span class="op">-</span>p2<span class="op">-</span>1),1,0.5,0
a1      <span class="opc">granule</span> p4<span class="op">*</span>k1,p5,p6,p7,p8,p9,p10,p11,p12,p13,p14,p15,\
        p16,p17,p18,p19,p20,p21,p22,p23,p24
a2      <span class="opc">granule</span> p4<span class="op">*</span>k1,p5,p6,p7,p8,p9,p10,p11,p12,p13,p14,p15,\
        p16,p17,p18,p19, p20<span class="op">+</span>0.17,p21,p22,p23,p24
<span class="opc">outs</span> a1,a2
<span class="oblock">endin</span>


<span class="csdtag">&lt;/CsInstruments&gt;</span>
<span class="csdtag">&lt;CsScore&gt;</span>

<span class="comment">; f statement read sound file mary.wav in the SFDIR </span>
<span class="comment">; directory into f-table 1</span>
<span class="stamnt">f</span>1      0 262144 1 "mary.wav" 0 0 0
<span class="stamnt">i</span>1      0 10 2000 64 0.5 0 0 1 4 0 0.005 5 0.01 50 0.02 50 30 30 0.39 \
        1 1.42 0.29 2
<span class="stamnt">e</span>


<span class="csdtag">&lt;/CsScore&gt;</span>
<span class="csdtag">&lt;/CsoundSynthesizer&gt;</span>
</pre>
          </div>
        </div>
        <p><br class="example-break" />
   </p>
        <p>
     The above example reads a sound file called <span class="emphasis"><em>mary.wav</em></span> into wavetable number 1 with 262,144 samples. It generates 10 seconds of stereo audio output using the wavetable. In the orchestra file, all parameters required to control the synthesis are passed from the score file. A <span class="emphasis"><em>linseg</em></span> function generator is used to generate an envelope with 0.5 second of linear attack and decay. Stereo effect is generated by using different seeds for the two <span class="emphasis"><em>granule</em></span> function calls. In the example, 0.17 is added to p20 before passing into the second <span class="emphasis"><em>granule</em></span> call to ensure that all of the random offset events are different from the first one.
   </p>
        <p>
     In the score file, the parameters are interpreted as:

     </p>
        <div class="informaltable">
          <table border="1">
            <colgroup>
              <col />
              <col />
            </colgroup>
            <thead>
              <tr>
                <th>Parameter</th>
                <th>Interpreted As</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td>p5 (<span class="emphasis"><em>ivoice</em></span>)</td>
                <td>the number of voices is set to 64</td>
              </tr>
              <tr>
                <td>p6 (<span class="emphasis"><em>iratio</em></span>)</td>
                <td>set to 0.5, it scans the wavetable at half of the speed of the audio output rate</td>
              </tr>
              <tr>
                <td>p7 (<span class="emphasis"><em>imode</em></span>)</td>
                <td>set to 0, the grain pointer only move forward</td>
              </tr>
              <tr>
                <td>p8 (<span class="emphasis"><em>ithd</em></span>)</td>
                <td>set to 0, skipping the thresholding process</td>
              </tr>
              <tr>
                <td>p9 (<span class="emphasis"><em>ifn</em></span>)</td>
                <td>set to 1, function table number 1 is used</td>
              </tr>
              <tr>
                <td>p10 (<span class="emphasis"><em>ipshift</em></span>)</td>
                <td>set to 4, four different pitches are going to be generated</td>
              </tr>
              <tr>
                <td>p11 (<span class="emphasis"><em>igskip</em></span>)</td>
                <td>set to 0 and p12 (<span class="emphasis"><em>igskip_os</em></span>) is set to 0.005, no skipping into the wavetable and a 5 mSec random offset is used</td>
              </tr>
              <tr>
                <td>p13 (<span class="emphasis"><em>ilength</em></span>)</td>
                <td>set to 5, 5 seconds of the wavetable is to be used</td>
              </tr>
              <tr>
                <td>p14 (<span class="emphasis"><em>kgap</em></span>)</td>
                <td>set to 0.01 and p15 (<span class="emphasis"><em>igap_os</em></span>) is set to 50, 10 mSec gap with 50% random offset is to be used</td>
              </tr>
              <tr>
                <td>p16 (<span class="emphasis"><em>kgsize</em></span>)</td>
                <td>set to 0.02 and p17 (<span class="emphasis"><em>igsize_os</em></span>) is set to 50, 20 mSec grain with 50% random offset is used</td>
              </tr>
              <tr>
                <td>p18 (<span class="emphasis"><em>iatt</em></span>) and p19 (<span class="emphasis"><em>idec</em></span>)</td>
                <td>set to 30, 30% of linear attack and decade is applied to the grain</td>
              </tr>
              <tr>
                <td>p20 (<span class="emphasis"><em>iseed</em></span>)</td>
                <td>seed for the random number generator is set to 0.39</td>
              </tr>
              <tr>
                <td>p21 - p24</td>
                <td>pitches set to 1 which is the original pitch, 1.42 which is a 5th up, 0.29 which is a 7th down and finally 2 which is an octave up.</td>
              </tr>
            </tbody>
          </table>
        </div>
        <p>
   </p>
      </div>
      <div class="refsect1">
        <a id="idp113678000"></a>
        <h2>Credits</h2>
        <p>Author: Allan Lee</p>
        <p>Belfast</p>
        <p>1996</p>
        <p>New in version 3.35</p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="grain3.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="OpcodesTop.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="guiro.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">grain3 </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> guiro</td>
        </tr>
      </table>
    </div>
  </body>
</html>
